PSET

Section: Miscellaneous Library Functions (3X)
Updated: 25 September 1992
Index Return to Main Contents

NAME

pset_create, pset_destroy, pset_add, pset_insert, pset_remove, pset_delete, pset_remove_index, pset_clear, pset_count, pset_pointer, pset_freeall - routines that handle pointer sets

SYNOPSIS

#include "pset.h"

pset_h pset_create( alloc_start, alloc_step )
unsigned alloc_start, alloc_step ;

void pset_destroy( pset )
pset_h pset ;

pset_static(name)

ANY_TYPE *pset_add( pset, ptr )
pset_h pset ;
ANY_TYPE *ptr ;

void *pset_insert( pset, ptr )
pset_h pset ;
void *ptr ;

void pset_remove( pset, ptr )
pset_h pset ;
ANY_TYPE *ptr ;

void pset_delete( pset, ptr )
pset_h pset ;
void *ptr ;

void pset_remove_index( pset, index )
pset_h pset ;
unsigned index ;

void pset_clear( pset )
pset_h pset ;

unsigned pset_count( pset )
pset_h pset ;

void *pset_pointer( pset, index )
pset_h pset ;
unsigned index ;

void pset_freeall( pset )
pset_h pset ;

DESCRIPTION

This library provides functions that handle sets of pointers. Pointers can be inserted and deleted from sets and the sets can be enumerated. Pointers are inserted in sets in no particular order. However it is guaranteed that a sequence of insertions will result in a set which if enumerated will provide the pointers in the same order in which they were inserted (assuming no intervening deletions).

pset_create() creates a pointer set. alloc_start determines the initial table size, and alloc_step determines the amount by which the set size is increased in case of overflow. If any of these parameters is 0, a default value is used.

pset_destroy() destroys the specified pointer set.

pset_static is a macro that defines a static pointer set with name as its handle. There should be no white space inside the parhntheses. The storage class of the pointer set is static and its scope is global. If you want a different scope (like a file scope or a function scope) you should precede this definition with the keyword static. Finally, it is an error to give a static pointer set handle to pset_destroy().

pset_add() is a macro that adds a pointer to the specified set. The pointer can be of any type.

pset_insert() inserts a pointer to the specified set. This is the same operation as pset_add().

pset_remove() removes a pointer from the specified set.

pset_delete() deletes a pointer from the specified set. This is the same operation as pset_remove().

pset_remove_index() removes the pointer that is at position index in the set. index should be in the range [0, pset_count( pset )) (but there is no check to enforce this). After this operation, the index position will be occupied by another pointer.

pset_clear() removes all pointers from the specified set.

pset_count() returns the number of pointers in the specified set.

pset_pointer() returns the pointer at position index in the specified set. index must be between 0 and pset_count( pset )

pset_freeall() applies free(3) on all pointers in the specified set. Obviously, all such pointers should have been returned by malloc(3).

RETURN VALUES

pset_h is a pointer type. Functions that return pset_h will return NULL to indicate an error.

pset_create() returns a pointer set handle or NULL if it fails.

pset_add() returns its second argument if successful or NULL if it fails.

pset_insert() returns its second argument if successful or NULL if it fails.

pset_count() always returns the size of the set.

pset_pointer() always returns a pointer. There is no check if the specified index is within range.

BUGS

pset_add(), pset_remove(), pset_remove_index(), pset_count(), pset_freeall(), pset_clear(), and pset_pointer() are macros, therefore the & operator cannot be applied on them.

pset_add() evaluates its pointer argument more than once.

This document was created by man2html, using the manual pages.
Time: 06:35:29 GMT, May 19, 2025